3D Graphics Programming with QuickDraw 3D 1.5.4

Manipulating Textures and Bitmaps

QuickDraw 3D RAVE provides routines that you can use to create and dispose of texture maps and bitmaps. It also provides routines that you can use to bind color lookup tables to texture maps and bitmaps.

QATextureNew

You can use the QATextureNew function to create a new texture map.



 
TQAError QATextureNew (

                     const TQAEngine *engine, 

                     unsigned long flags, 

                     TQAImagePixelType pixelType, 

                     const TQAImage images[], 

                     TQATexture **newTexture);

engine: A drawing engine.
flags: A set of bit flags specifying features of the new texture map. See "Texture Flags Masks" for complete information.
pixelType: The type of pixels in the new texture map. See "Pixel Types" for a description of the values you can pass in this parameter.
images: An array of pixel images to use for the new texture map. The values in the width and height fields of these structures must be an even power of 2.
newTexture: On entry, the address of a pointer variable. On exit, that variable points to a new texture map. If a new texture map cannot be created, *newTexture is set to the value NULL .

DESCRIPTION

The QATextureNew function returns, through the newTexture parameter, a new texture map associated with the drawing engine specified by the engine parameter. You can use the returned texture map to set the value of the kQATag_Texture state variable.

The flags parameter specifies a set of texture map features. If the kQATexture_Lock bit in that parameter is set but the drawing engine cannot guarantee that the texture will remain locked in memory, the QATextureNew function returns an error.

If the kQATexture_Mipmap bit of the flags parameter is clear, the images parameter points to a single pixel image that defines the texture map. If the kQATexture_Mipmap bit is set, the images parameter points to an array of pixel images of varying pixel depths. The first element in the array must be the mipmap page having the highest resolution, with a width and height that are even powers of 2. Each subsequent pixel image in the array should have a width and height that are half those of the previous image (with a minimum width and height of 1).

SPECIAL CONSIDERATIONS

QATextureNew does not automatically copy the pixmap data pointed to by the images parameter. As a result, you should not release or reuse the storage occupied by the pixel images until you've called QATextureDetach . Note, however, that QATextureNew does copy all of the information contained in the TQAImage structures in the array, so you can free or reuse that memory after QATextureNew completes successfully.

QATextureDetach

You can use the QATextureDetach function to detach a texture map from a drawing engine.



 
TQAError QATextureDetach (const TQAEngine *engine, TQATexture *texture);

engine: A drawing engine.
texture: A texture map.

DESCRIPTION

The QATextureDetach function causes the drawing engine specified by the engine parameter to copy the data associated with the texture map specified by the texture parameter. Once the data are copied, you can reuse or dispose of the memory you originally specified in a call to QATextureNew .

QATextureBindColorTable

You can use the QATextureBindColorTable function to bind a color lookup table to a texture map.



 
TQAError QATextureBindColorTable (

                     const TQAEngine *engine,

                     TQATexture *texture,

                     TQAColorTable *colorTable);

engine: A drawing engine.
texture: A texture map.
colorTable: A color lookup table (as returned by a previous call to QAColorTableNew ).

DESCRIPTION

The QATextureBindColorTable function binds the color lookup table specified by the colorTable parameter to the texture map specified by the texture parameter. Before you can draw any texture map whose pixel type is either kQAPixel_CL4 or kQAPixel_CL8 , you must bind a color lookup table to it. In addition, the type of the specified color lookup table must match that of the pixel type of the texture map to which it is bound. For example, a color lookup table of type kQAColorTable_CL8_RGB32 can be bound only to a texture map whose pixel type is kQAPixel_CL8 .

QATextureDelete

You can use the QATextureDelete function to delete a texture map.



 
void QATextureDelete (const TQAEngine *engine, TQATexture *texture);

engine: A drawing engine.
texture: A texture map.

DESCRIPTION

The QATextureDelete function deletes the texture map specified by the texture parameter from the drawing engine specified by the engine parameter.

QABitmapNew

You can use the QABitmapNew function to create a new bitmap.



 
TQAError QABitmapNew (

                     const TQAEngine *engine, 

                     unsigned long flags, 

                     TQAImagePixelType pixelType, 

                     const TQAImage *image, 

                     TQABitmap **newBitmap);

engine: A drawing engine.
flags: A set of bit flags specifying features of the new bitmap. See "Bitmap Flags Masks" for complete information
pixelType: The type of pixels in the new bitmap. See "Pixel Types" for a description of the values you can pass in this parameter.
image: A pixel image to use for the new bitmap. The width and height fields of this image can have any values greater than 0.
newBitmap: On entry, the address of a pointer variable. On exit, that variable points to a new bitmap. If a new bitmap cannot be created, *newBitmap is set to the value NULL .

DESCRIPTION

The QABitmapNew function returns, through the newBitmap parameter, a pointer to a new bitmap associated with the drawing engine specified by the engine parameter. You can draw the returned bitmap by calling the QADrawBitmap function.

The flags parameter specifies a set of bitmap features. If the kQABitmap_Lock bit in that parameter is set but the drawing engine cannot guarantee that the bitmap will remain locked in memory, the QABitmapNew function returns an error.

SPECIAL CONSIDERATIONS

QABitmapNew does not automatically copy the pixmap data pointed to by the images parameter. As a result, you should not release or reuse the storage occupied by the pixel image until you've called QABitmapDetach . Note, however, that QABitmapNew does copy all of the information contained in the TQAImage structure, so you can free or reuse that memory after QABitmapNew completes successfully.

QABitmapDetach

You can use the QABitmapDetach function to detach a bitmap from a drawing engine.



 
TQAError QABitmapDetach (const TQAEngine *engine, TQABitmap *bitmap);

engine: A drawing engine.
bitmap: A bitmap.

DESCRIPTION

The QABitmapDetach function causes the drawing engine specified by the engine parameter to copy the data associated with the bitmap specified by the bitmap parameter. Once the data are copied, you can reuse or dispose of the memory you originally specified in a call to QABitmapNew .

QABitmapBindColorTable

You can use the QABitmapBindColorTable function to bind a color lookup table to a bitmap.



 
TQAError QABitmapBindColorTable (

                     const TQAEngine *engine,

                     TQABitmap *bitmap,

                     TQAColorTable *colorTable);

engine: A drawing engine.
bitmap: A bitmap.
colorTable: A color lookup table (as returned by a previous call to QAColorTableNew ).

DESCRIPTION

The QABitmapBindColorTable function binds the color lookup table specified by the colorTable parameter to the bitmap specified by the bitmap parameter. Before you can draw any bitmap whose pixel type is either kQAPixel_CL4 or kQAPixel_CL8 , you must bind a color lookup table to it. In addition, the type of the specified color lookup table must match that of the pixel type of the bitmap to which it is bound. For example, a color lookup table of type kQAColorTable_CL8_RGB32 can be bound only to a bitmap whose pixel type is kQAPixel_CL8 .

QABitmapDelete

You can use the QABitmapDelete function to delete a bitmap.



 
void QABitmapDelete (const TQAEngine *engine, TQABitmap *bitmap);

engine: A drawing engine.
bitmap: A bitmap.

DESCRIPTION

The QABitmapDelete function deletes the bitmap specified by the bitmap parameter from the drawing engine specified by the engine parameter.